Спринт 2/18 → Тема 5/6: Требования к коду → Урок 5/7

Пакеты и модули

Тимур
Снова привет! Хочу сказать, тобой проделана отличная работа над проектом. У тебя неплохо получилось оформить код и сделать его более читаемым. Пора расширить возможности программы.
Наша игра работает в терминале, но это не значит, что её нельзя напичкать графикой. У нас есть гейм-дизайнер, и для проекта, над которым ты работаешь, он написал модуль, который запускает заставку для игры. Это не совсем привычная заставка, она состоит из печатных символов. Твоя задача — подключить этот модуль к программе.
Скачайте модуль start_game_banner.py. Создайте в корневой директории проекта character_creation_module/ папку graphic_arts/. Добавьте в эту папку только что скачанный модуль. Структура проекта должна получиться такой:
character_creation_module/
 ├── graphic_arts/
 |   └── start_game_banner.py
 ├── venv/
 ├── .gitignore/
 ├── main.py
 ├── pytest.ini
 ├── README.md
 └── test_module.py
Модуль добавлен, но пока он сам по себе, то есть не подключён к проекту, а значит, посмотреть во всей красе на его работу не получится. Итак, пора разобраться, что же вообще такое модуль и как подключить его к проекту.

Что такое модуль

Когда над проектом работает несколько программистов, обычно каждый отвечает за свою часть кода. Если все будут работать в одном файле, рано или поздно это приведёт к проблемам. Например, разные разработчики могут дать одинаковые имена переменным, это приведёт к конфликту имён, и программа будет работать не так, как ожидалось. Также в коде такого проекта может оказаться несколько функций, которые отвечают за одно и то же, и сразу отследить это не получится. А как же DRY?
Чтобы избежать подобных ситуаций, программисты разбивают проект на модули.
Модуль в Python — это отдельный файл с расширением .py, который содержит код программы.
Модули можно разделить на три типа:
С модулями стандартной библиотеки Python вы уже работали. Например, вы сталкивались с модулем datetime.
В стандартной библиотеке содержатся модули, написанные на Cи, которые отвечают за доступ к системным функциям, например функциям ввода-вывода. Без подобных модулей программисты на Python не смогли бы пользоваться этими функциями. Также в стандартной библиотеке есть модули, написанные на Python. Они помогают решать многие задачи, с которыми ежедневно сталкиваются разработчики на Python. Например, модуль datetime предоставляет инструменты управления значениями даты и времени.
Сторонние модули — это модули, которые написали другие разработчики. Такие модули можно установить через пакетный менеджер или скачать с GitHub.
Сторонние модули чаще всего пишут для того, чтобы расширить возможности стандартной библиотеки, например, для работы с искусственным интеллектом, графикой, интерфейсами устройств.
Такие модули помогают писать код быстрее, ведь нет необходимости «придумывать велосипед». Достаточно заглянуть на GitHub и поискать то, что нужно в данный момент. Также сторонние модули можно изменять под свои нужды и предлагать включать эти изменения в исходный код.
Пользовательские модули — это файлы с кодом, которые разработчик создаёт самостоятельно для конкретного проекта.
Подключение модулей
В каждом модуле содержатся свои функции и переменные. Эти функции и переменные можно импортировать из модуля в основной код программы.
В проекте character_creation_module вы использовали возможности модуля стандартной библиотеки random: подключали из него функцию randint.
PYTHON
# Из модуля random импортируем функцию randint.
from random import randint
...
По такому же принципу можно подключать функции из сторонних и пользовательских модулей.
Например, у вас есть два модуля, которые находятся в одной директории:
  • первый содержит две функции: одна функция складывает два числа, а вторая — вычитает одно число из другого:
PYTHON
# Эта функция складывает два числа.
def add_two_numbers(a, b):
    return a + b

# Эта функция вычитает одно число из другого.
def subtraction (a, b):
    return a - b
  • второй модуль обрабатывает и преобразует в число значения, которые пользователь вводит в терминал:
PYTHON
# В переменные записываются значения, которые пользователь вводит в терминал.
# Далее эти значения преобразовываются в число.
first_num = int(input())
second_num = int(input())
Задача — использовать функции сложения и вычитания из первого модуля во втором модуле, чтобы обработать те данные, которые введёт пользователь. Конечно, можно просто дописать код во втором модуле, и дело сделано. Но зачем писать код, который уже кто-то написал за вас? Импортируем функции из первого модуля во второй:
PYTHON
# Из файла ... импортируем функции ...
from имя_файла_первого_модуля_без_.py import add_two_numbers, subtraction

first_num = int(input())
second_num = int(input())

# Выводим результат на печать.
print(add_two_numbers( first_num, second_num))
print(subtraction( first_num, second_num))
Программа готова, и вам не пришлось переносить код из одного модуля в другой. Практично.

Папка с модулями — это пакет

Когда проект начинает разрастаться, разработчики для удобства собирают общие по тематике модули в одну папку внутри проекта. Такая папка называется пакетом (англ. package). В стандартной библиотеке тоже есть пакеты модулей, например, пакет email объединяет несколько модулей для управления сообщениями электронной почты.
В каждый пакет рекомендуется добавлять файл __init__.py. В официальной документации нет чёткого указания использовать этот файл, но он может быть полезен.
Например, в этот файл можно добавить описание пакета. У пакета email из стандартной библиотеки Python описание в __init__.py выглядит так
PYTHON
# Copyright (C) 2001-2007 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig@python.org

"""A package for parsing, handling, and generating email messages."""
Описание поможет вам или другим разработчикам быстро понять, для чего используются модули из пакета. Также описанные в пакете модули отображаются в подсказке в редакторе кода при импорте. Всё на виду — не нужно заглядывать внутрь пакета, чтобы понять, какие у него есть возможности.

Библиотека

В курсе вы довольно часто сталкивались с понятием «стандартная библиотека Python». Но что же такое библиотека? Разбираемся.
Библиотека — это совокупность модулей и пакетов, которые решают задачу в одной предметной области. Например, стандартная библиотека Python — это набор модулей и пакетов для решения популярных задач, с которыми ежедневно встречаются разработчики на Python. Не нужно писать код с нуля — достаточно подключить в проект готовый модуль или пакет. Удобно.
Есть и другие библиотеки, но всему своё время. Пока что для учёбы вам будет вполне достаточно стандартной библиотеки.
☝ Модуль — это python-файл, который содержит переменные, функции, классы и исполняемый код. Модули могут быть объединены в пакеты, а пакеты и модули, которые решают задачу в одной предметной области, — в библиотеки.

Вернёмся к проекту

Итак, сейчас в вашем проекте есть два модуля:
  • модуль main.py, он отвечает за создание персонажа игры;
  • модуль start_game_banner.py, который отвечает за анимацию.
Ваша задача — подключить модуль анимации к модулю создания персонажа игры.
Откройте файл main.py и доработайте в нём код:
PYTHON
# character_creation_module/main.py

from random import randint

# Новый импорт.
# Из модуля start_game_banner, который расположен в папке graphic_arts,
# импортируем функцию run_screensaver().
from graphic_arts.start_game_banner import run_screensaver

def attack(char_name: str, char_class: str) -> str:
    ...

def defence(char_name: str, char_class: str) -> str:
    ...

def special(char_name: str, char_class: str) -> str:
    ...

def start_training(char_name: str, char_class: str) -> str:
    ...

def choice_char_class() -> str:
    ...

def main() -> None:
    run_screensaver()
    print('Приветствую тебя, искатель приключений!')
    print('Прежде чем начать игру...')
    char_name: str = input('...назови себя: ')
    print(f'Здравствуй, {char_name}! '
          'Сейчас твоя выносливость — 80, атака — 5 и защита — 10.')
    print('Ты можешь выбрать один из трёх путей силы:')
    print('Воитель, Маг, Лекарь')
    char_class: str = choice_char_class()
    print(start_training(char_name, char_class))

main()
Теперь запустите программу командой:
BASH
python main.py
Вероятно, не всё пойдёт по плану…
BASH
Traceback (most recent call last):
  .....
ModuleNotFoundError: No module named 'asciimatics'
Ошибка. Она говорит, что модуля с именем asciimatics нет ни в виртуальном окружении, ни в файлах проекта.
Модуль asciimatics — сторонний. Чтобы всё заработало, его нужно установить в виртуальное окружение вашего проекта через пакетный менеджер. Сделайте это:
BASH
pip install asciimatics
Теперь asciimatics будет находиться в директории Windows —/Lib/site-packages/, Linux/MacOS — /Lib/версия_python/site-packages/ вашего виртуального окружения venv вместе с остальными установленными пакетами и библиотеками.
Снова запустите программу и посмотрите на результат.

if __name__ == '__main__'

Модули Python можно запускать как самостоятельные программы, а можно импортировать их целиком или только функции из них в другие модули.
Когда модуль запускается как самостоятельная программа, выполняется весь код целиком, как и полагается в интерпретаторе: построчно, команда за командой.
Возьмём для примера модуль module1.py с функцией special_calculation, которая складывает два числа и от их суммы отнимает 2:
PYTHON
def special_calculation(a, b):
    return a + b - 2

print('Модуль запущен')
print('Проверим работу функции')
# Запускается функция с разными значениями переменных a и b.
# Значения сравниваются с ожидаемым ответом.
print(5 == special_calculation(2, 5))
print(5 == special_calculation(2, 2))
print(4 == special_calculation(3, 3))
Если запустить этот модуль, то последовательно выведутся все принты:
BASH
Модуль запущен
Проверим работу функции
True
False
True
Функция special_calculation хоть и простая, но вполне может пригодиться и в другом модуле, например в module2.py. Тогда будет достаточно импортировать эту функцию, заново код переписывать не придётся:
PYTHON
# Из модуля module1.py импортируем функцию special_calculation.
from module1 import special_calculation

print("Основной модуль")
# Производим расчёты. 
coef = special_calculation(2, 5)
print(coef)
Результат выполнения программы будет таким:
BASH
Модуль запущен
Проверим работу функции
True
False
True
Основной модуль
5
Из вывода видно, что сначала вывелись результаты вызова функций, которые выполнялись в module1.py, а затем те, что выполнялись в module2.py. Вся эта информация нам ни к чему. Нам нужен только тот вывод, который относится к файлу module2.py.
В таких ситуациях следует использовать специальную конструкцию — if __name__ == '__main__'. Код, размещённый в теле этой конструкции, выполняется только тогда, когда модуль запускается как самостоятельная программа. То есть это «личный» код модуля.
Работает эта конструкция так. При запуске кода инициализируется специальная переменная __name__, по которой интерпретатор определяет, импортирован модуль или нет.
Если модуль запускается как самостоятельная программа, то этой переменной присваивается значение '__main__'. Если же модуль импортируется, то значение этой переменной равно названию модуля, в которую импортирован код.
Значит, если в модуле module1.py убрать код, который отвечает за вывод результата на печать, в конструкцию if __name__ == '__main__'...
PYTHON
def special_calculation(a, b):
    return a + b - 2

if __name__ == '__main__':
    print('Модуль запущен')
    print('Проверим работу функции')
    # Запуск функции с разными значениями
    # и сравнение их с ожидаемым ответом.
    print(5 == special_calculation(2, 5))
    print(5 == special_calculation(2, 2))
    print(4 == special_calculation(3, 3))
…то при запуске модуля как самостоятельной программы вывод на печать состоится…
BASH
Модуль запущен
Проверим работу функции
True
False
True
…а при импорте функции special_calculation() в модуль module2.py ничего лишнего не распечатается:
BASH
Основной модуль
5
В учебном проекте character_creation_module в модуле main.py есть функция main(). Эта функция отвечает за приветствие игрока. Такая функция нужна только при запуске конкретно этого модуля, в остальных случаях она навряд ли пригодится, а вот другие функции из модуля могут понадобиться. Чтобы приветствие не выводилось когда ни попадя, следует вынести его под if __name__ == '__main__'. Сделайте это:
PYTHON
# character_creation_module/main.py

# Вместо...
def main() -> None:
    print('Приветствую тебя, искатель приключений!')
    print('Прежде чем начать игру...')
    char_name: str = input('...назови себя: ')
    print(f'Здравствуй, {char_name}! '
          'Сейчас твоя выносливость — 80, атака — 5 и защита — 10.')
    print('Ты можешь выбрать один из трёх путей силы:')
    print('Воитель, Маг, Лекарь')
    char_class: str = choice_char_class()
    print(start_training(char_name, char_class))

main()

# ...запишите:
if __name__ == '__main__':
    run_screensaver()
    print('Приветствую тебя, искатель приключений!')
    print('Прежде чем начать игру...')
    char_name: str = input('...назови себя: ')
    print(f'Здравствуй, {char_name}! '
          'Сейчас твоя выносливость — 80, атака — 5 и защита — 10.')
    print('Ты можешь выбрать один из трёх путей силы:')
    print('Воитель, Маг, Лекарь')
    char_class: str = choice_char_class()
    print(start_training(char_name, char_class))
На работоспособность вашей программы такие манипуляции не повлияют. Убедитесь в этом: запустите проект, всё должно работать, как и прежде.
Модули, пакеты, библиотеки — теперь эти слова обрели для вас смысл. Базовые понятия программирования — фундамент знаний хорошего разработчика.